﻿// =============================================
// 引入 UnityEngine 命名空间，提供基础功能，如序列化、范围限制等
// =============================================
using UnityEngine;

// =============================================
// 定义一个可序列化的配置类：ShadowSettings
// 该类用于定义和控制定向光源阴影的各种渲染参数
// 被设计为可在 Inspector 中直观调整，常用于自定义渲染管线中的阴影模块
// =============================================
[System.Serializable]
public class ShadowSettings
{
	// =============================================
	// 枚举：MapSize —— 定义阴影贴图（Shadow Atlas）的分辨率大小选项
	// 提供一系列 2 的幂次方尺寸，适配不同精度与性能需求
	// =============================================
	public enum MapSize
	{
		_256 = 256,    // 256 x 256，低性能设备或小物体可用
		_512 = 512,    // 512 x 512
		_1024 = 1024,  // 1024 x 1024，常用中等精度
		_2048 = 2048,  // 2048 x 2048，较高精度，适合主角、重要场景
		_4096 = 4096,  // 4096 x 4096，高精度，大场景远景也可接受
		_8192 = 8192   // 8192 x 8192，极高精度，一般用于大世界主光源，性能开销大
	}

	// =============================================
	// 枚举：FilterMode —— 定义定向光源阴影的滤波（PCF）模式，控制阴影边缘的柔和程度
	// PCF：Percentage Closer Filtering，通过采样多个点实现软阴影
	// =============================================
	public enum FilterMode
	{
		PCF2x2,  // 2x2 = 4 个采样点，最硬的阴影，性能最好
		PCF3x3,  // 3x3 = 9 个采样点，轻微柔和
		PCF5x5,  // 5x5 = 25 个采样点，更柔和
		PCF7x7   // 7x7 = 49 个采样点，最柔和，但性能开销最大
	}

	// =============================================
	// 属性：maxDistance
	// 作用：定义阴影能够投射的最大距离（世界单位）
	// 超出此距离的物体将不再产生阴影，用于优化性能
	// 最小值限制为 0.001f，避免设置为 0 导致计算异常
	// =============================================
	[Min(0.001f)]
	public float maxDistance = 100f; // 默认 100 米，可根据场景大小调整

	// =============================================
	// 属性：distanceFade
	// 作用：定义阴影在接近最大距离时，开始淡出的速率或距离阈值
	// 用于实现阴影从清晰到逐渐消失的过渡效果，提升视觉合理性
	// 范围限制在 [0.001f, 1f]，值越小淡出越快
	// =============================================
	[Range(0.001f, 1f)]
	public float distanceFade = 0.1f; // 默认 0.1，控制淡出敏感度

	// =============================================
	// 嵌套结构体：Directional
	// 专门用于配置 **定向光源（Directional Light，如太阳光）的阴影参数**
	// =============================================
	[System.Serializable]
	public struct Directional
	{
		// =========================================
		// 属性：atlasSize
		// 作用：定义定向光源阴影贴图图集（Atlas）的分辨率
		// 可选值来自 MapSize 枚举，比如 1024、2048 等
		// 决定了阴影的精细程度与显存占用
		// =========================================
		public MapSize atlasSize;

		// =========================================
		// 属性：filter
		// 作用：定义该光源阴影使用的 PCF 滤波模式，控制阴影边缘柔和度
		// 可选值：PCF2x2（硬阴影）、PCF3x3、PCF5x5、PCF7x7（最柔和）
		// =========================================
		public FilterMode filter;

		// =========================================
		// 属性：cascadeCount
		// 作用：定义定向光源使用的 **级联阴影（Cascaded Shadows）数量**
		// 通常为 3~4 个，将摄像机视锥体按距离分为多个层级，每层使用独立的阴影贴图
		// 级联数越多，远近景阴影质量越好，但性能开销越大
		// 范围限制为 [1, 4]
		// =========================================
		[Range(1, 4)]
		public int cascadeCount;

		// =========================================
		// 属性：cascadeRatio1, cascadeRatio2, cascadeRatio3
		// 作用：定义前 3 个级联在摄像机视锥体中的 **分割比例**
		// 用于控制每个级联负责的远近范围，比如：
		// - cascadeRatio1 = 0.1 → 第 1 级联负责最近 10% 的视野
		// - cascadeRatio2 = 0.25 → 第 2 级联负责接下来的 25%
		// - cascadeRatio3 = 0.5 → 第 3 级联负责再接下来的 50%
		// 剩余部分由第 4 级联（如有）负责
		// 这些比例决定了级联之间的边界位置
		// =========================================
		[Range(0f, 1f)]
		public float cascadeRatio1, cascadeRatio2, cascadeRatio3;

		// =========================================
		// 属性：CascadeRatios
		// 作用：将上面三个级联比例封装为一个 Vector3，便于在代码中统一传递与使用
		// 返回：new Vector3(cascadeRatio1, cascadeRatio2, cascadeRatio3)
		// =========================================
		public Vector3 CascadeRatios =>
			new Vector3(cascadeRatio1, cascadeRatio2, cascadeRatio3);

		// =========================================
		// 属性：cascadeFade
		// 作用：定义级联之间阴影混合时的 **淡出距离或强度**
		// 用于实现相邻级联之间的平滑过渡，避免硬边界（比如远处阴影突然切换）
		// 范围限制为 [0.001f, 1f]
		// =========================================
		[Range(0.001f, 1f)]
		public float cascadeFade;

		// =========================================
		// 枚举：CascadeBlendMode
		// 作用：定义级联阴影之间的混合方式，控制过渡效果
		// - Hard：硬切换，无混合（性能最好，但可能有明显边界）
		// - Soft：软混合（通过距离淡入淡出，较平滑）
		// - Dither：抖动混合（通过像素级抖动实现自然过渡，视觉柔和但可能有噪点）
		// =========================================
		public enum CascadeBlendMode
		{
			Hard,    // 硬过渡，无混合
			Soft,    // 软过渡，基于距离淡入淡出
			Dither   // 抖动过渡，通过像素抖动实现自然感
		}

		// =========================================
		// 属性：cascadeBlend
		// 作用：当前使用的级联混合模式，来自 CascadeBlendMode 枚举
		// =========================================
		public CascadeBlendMode cascadeBlend;
	}

	// =============================================
	// 属性：directional
	// 作用：定义当前项目中 **定向光源（如太阳光）的阴影配置**
	// 是 Directional 结构体的一个实例，提供默认值，可在 Inspector 中调整
	// =============================================
	public Directional directional = new Directional
	{
		atlasSize = MapSize._1024,          // 默认阴影图集分辨率：1024x1024
		filter = FilterMode.PCF2x2,         // 默认使用 2x2 PCF，硬阴影，性能优先
		cascadeCount = 4,                   // 默认使用 4 个级联
		cascadeRatio1 = 0.1f,               // 第1级联：10%
		cascadeRatio2 = 0.25f,              // 第2级联：25%
		cascadeRatio3 = 0.5f,               // 第3级联：50%
		cascadeFade = 0.1f,                 // 级联间淡出强度：0.1
		cascadeBlend = Directional.CascadeBlendMode.Hard // 默认级联混合模式：硬切换
	};
}